In the article "Implementing MVC Designs Using OWL's Doc/View Architecture,", we show how you can separate the core code of your application from the user-interface code that creates views, displays data, and responds to user input. In order to help manage the creation, destruction, and interaction of documents and their associated views, Borland provides the TDocManager and TDocTemplate classes.
Much of the work that these classes do is very complex, and therefore seems quite mysterious. Fortunately, you won't need to worry about the details of their operation, unless you want to customize their behavior or just learn how they work.
In this article, we'll briefly examine how the TDocManager
and TDocTemplate classes work with your document and
view classes. First, we'll review how a Doc/View application
creates a new document and its associated view, and then we'll
consider what happens when you open an additional view of that
document.
When you choose New from a Doc/View application's File menu, a fascinating sequence of function calls begins. To help you visualize how control flows during this process, follow the function call diagram that appears in Figure A.
Figure A - When you create a new document, the Doc/View classes do most of the work.
First, the current TDocManager object uses its CmFileNew() member function to respond to the CM_FILENEW message from Windows. This function in turn calls the member function CreateAnyDoc().
If you've defined more than one document template, the CreateAnyDoc() function builds a list of document types and then calls the SelectDocType() function. This function displays the list of document types in a pop-up menu from which the user selects the new document's type.
After the user selects a document type (or if there's only one document template available), the CreateAnyDoc() function calls the CreateDoc() member function of the appropriate document template object (the object you instantiate right after you define the document template class). By default, the CreateDoc() function calls the document template's InitDoc() member function.
The document template's member function InitDoc() in turn calls the member function CreateView(). (If you create the document template object using the dnNoAutoView flag, the InitDoc() function will call the TDocManager object's member function CreateAnyView() to prompt the user for a view type. This is similar to what happens when you create a new view for an existing document.)
The document template's CreateView() member function calls the InitView() function to create the new view object, and then it calls the document object's InitView() function. The document's InitView() member function calls the TDocManager object's PostEvent() function to post an EV_OWLVIEW event that contains the dnCreate flag and a pointer to the new view object.
By the way, don't confuse the TDocTemplate base class with the TDocTemplateT<> class that Borland derived from it. The TDocTemplate class defines the CreateDoc() and CreateView() member functions in order to call the corresponding InitDoc() or InitView() function from the TDocTemplateT<> class. This is because the TDocTemplateT<> class knows (via its template parameters) the class names of the document and view classes you used in the DEFINE_DOC_TEMPLATE macro.
Finally, one of the objects in the current event-handling chain
(typically, it's the application object) processes the
EV_OWLVIEW event with a message response function similar to EvNewView().
In order to display the window object that the view will use for
presenting its data, EvNewView() (or some other response
function that handles the EV_OWLVIEW event) calls the GetWindow()
member function of the view object whose address appears in the
message, and the EvNewView() member function displays
the window. Now each function returns, and the application is
ready to continue with the new view window in place.
Once you've opened a document, the Doc/View classes provide a mechanism for creating a new view of that same document. The new view can be the same type as the existing view, but it doesn't have to be.
Typically, you'll want to display a menu command for creating a new document view. However, if you'd like the TDocManager object to help you with this process, you'll need to assign a special constantCM_VIEWCREATEto the menu command. To see how the control flows when you choose this command, follow the function call diagram that appears in Figure B.
Figure B - When you create a new view of an existing document, the Doc/View classes still do most of the work.
First, the current TDocManager object uses its CmViewCreate() member function to respond to the CM_VIEWCREATE message from Windows. This function in turn calls the CreateAnyView() member function.
If you've defined more than one document template, the CreateAnyView() function builds a list of view types and then calls the SelectViewType() function. This function displays the list of document types in a pop-up menu from which the user will select the new view's document type. (If you specify the dtNoAutoView flag when you create a document template, you'll choose the view type the same way.)
When the user selects a view type, the CreateAnyView()
function calls the CreateView() member function of the
appropriate document template object. From this point, the Doc/View
classes call the same sequence of functions that they call to
create the view for a new document.
Copyright (c) 1996 The Cobb Group, a division of Ziff-Davis Publishing Company. All rights reserved. Reproduction in whole or in part in any form or medium without express written permission of Ziff-Davis Publishing Company is prohibited. The Cobb Group and The Cobb Group logo are trademarks of Ziff-Davis Publishing Company.